home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 23 / CU Amiga - Super CD-ROM 23 (June 1998).iso / CUCD / Online / rxsocket / rxsocket.doc < prev    next >
Encoding:
Text File  |  1998-04-08  |  33.2 KB  |  1,208 lines
  1. ------------------------------------------------------------------------------------
  2.  
  3.                         RXSOCKET.LIBRARY version 1.6
  4.                                MINI-MINI DOC
  5.  
  6. ------------------------------------------------------------------------------------
  7.  
  8.                                   LECTURE
  9.  
  10.             THIS SOFTWARE AND INFORMATION ARE PROVIDED "AS IS";
  11.                           NO WARRANTIES ARE MADE.
  12.               ALL USE IS AT YOUR OWN RISK, AND NO LIABILITY OR
  13.                          RESPONSIBILITY IS ASSUMED.
  14.  
  15. ------------------------------------------------------------------------------------
  16.  
  17.                                    INDEX
  18.  
  19.      1. Introdution
  20.      2. Installation
  21.      3. System Requirements
  22.      4. Author
  23.      5. Distribution
  24.      6. Terms
  25.      7. Bugs
  26.      8. Structures and value of arguments
  27.      9. Functions in aplhabetic order
  28.     10. Thanks
  29.     11. Bibliography
  30.     12. To do
  31.     13. Note
  32.     14. Last minute
  33.  
  34. ------------------------------------------------------------------------------------
  35.  
  36. 1. Introdution
  37.  
  38.     The goal of this library is to offer a set of socket functions to
  39.     arexx-macro.
  40.  
  41.     It makes easy to access the Internet from an arexx macro.
  42.     The functions of this library directly call socket.library functions,
  43.     so this doc does not want to be an introdution to socket.library,
  44.     but just an explanation about the rexx library functions.
  45.  
  46.     The enviroiment is macro-private. Each macro opens the socket.library
  47.     and has a list of "things" that must be freed on exit.
  48.  
  49.     The way used to handle argument or results from function is:
  50.  
  51.     - when the originale socket.library function wants a non-structure
  52.       as argument, that argument is given to the function;
  53.     - when the original socket.library function wants a structure as
  54.       argument, a valid arexx variable name is the argument for that
  55.       struct; various fields of that variable name must be set;
  56.  
  57.     - when the originale socket.library returns an integer, that integer
  58.       is returned;
  59.     - when the originale socket.library returns a structure, a valid arexx
  60.       varable name is passed as argument to the function and various
  61.       fields of that setm are set by the function.
  62.  
  63.     This is a general policy in my rexx library and tries to emulate
  64.     the AmigaOS    tags programming way.
  65.  
  66.  
  67.     The library offers quite all the bsdsocket.library functions,
  68.      and some other function of a higher level (hehe just a couple
  69.     for now). The function dos not directly support raw packet, or
  70.     protocolls different from tcp, udp, but creating a memory
  71.     block and filling it by hands makes use of raw packets possible.
  72.  
  73.  
  74. ------------------------------------------------------------------------------------
  75.  
  76. 2. Installation
  77.  
  78.     No installation script is given.
  79.  
  80.     To install the library:
  81.     - copy rxsocket.library to libs:
  82.     - write in a shell:
  83.         rx "call addlib('rxsocket.library',0,-30)
  84.  
  85. ------------------------------------------------------------------------------------
  86.  
  87. 3. System Requirements
  88.  
  89.     The library needs AmigaOS>2.
  90.     The library is tested on miami.
  91.     It should work on AmiTCP.
  92.     It should work on termiteTCP ver 1.50, but same functions
  93.     are not avaible.
  94.  
  95. ------------------------------------------------------------------------------------
  96.  
  97. 4. Author
  98.  
  99.     Alfonso Ranieri
  100.  
  101.     E-Mail: alfier@iol.it
  102.  
  103.    You can find alfie (hiu, theQ) at:
  104.    - dalnet #amichat
  105.    - ircnet #amigaita
  106.    - ircnet #amyita
  107.  
  108. ------------------------------------------------------------------------------------
  109.  
  110. 5. Distribution
  111.  
  112.     rxsocket.library is FreeWare.
  113.  
  114.     You are free to detribute it as long as the original archive is
  115.     kept intact. Commercial use or its inclusion in other software
  116.     package    is prohibited without prior consens from the Author.
  117.  
  118. ------------------------------------------------------------------------------------
  119.  
  120. 6. Terms
  121.  
  122.     In this doc same terms need explanation:
  123.  
  124.     - stemName a valid arexx variable name
  125.       i.e. var, var.0, var.name, var
  126.  
  127.     - socket the socket numeric value returned from
  128.       socket(), ObtainSocket()
  129.  
  130.     - addr the integer arexx number returned from resolve() inet_addr()
  131.       and in various stem fileds. It is the u_long internet address you
  132.       use as argument for various functions. Don't make any assumption
  133.       on its value, because this is an arexx signed integer rather than
  134.       a c u_long, just compare it to -1 to know if it is bad.
  135.  
  136.     - types of arguments the type used are:
  137.         D any data            none
  138.         N numeric              /N
  139.         S symbol            /S arexx valid symbol
  140.         V stemName            /V arexx valid symbol as S but with length<20
  141.  
  142. ------------------------------------------------------------------------------------
  143.  
  144. 7. Bugs
  145.  
  146.     There are bugs in our wonderfull kernel.
  147.     There are bugs in very expansive commerciale products.
  148.  
  149.     Why shouldn't they be here?
  150.  
  151.     This is just quite a beta version, tested, but not so much.
  152.  
  153.     There is actually a well known problems:
  154.  
  155.     - on miami after a ReleaseSocket()/ObtainSocket() if the socket
  156.       obtained is passed to connect() an enforcer hit cames out.
  157.       This is a problem of miami, not mine.
  158.  
  159.     If you find bugs (and i am sure you'll do) write me asap, please.
  160.  
  161. ------------------------------------------------------------------------------------
  162.  
  163. 8. Structures and value of arguments passed or returned
  164.  
  165.     Actually 4 structures are passed or returned to/from functions.
  166.     They are the socket.library structures:
  167.     - struct hostent        returned by gethostbyname()
  168.     - struct servent         returned by getservbyname(), getservbynumber()
  169.     - struct protoent         returned by getprotobyname(), getprotobynumber()
  170.     - struct sockaddr_in    passed and returned to/from various functions
  171.  
  172.     As i said above, i emulate structure as arexx stemName;
  173.     an example will help:
  174.  
  175.     we want to get the local protoent of the echo tcp service
  176.     so we need a call to  getservbyname() passing it a stemName (see Terms)
  177.  
  178.     ---------------
  179.  
  180.     if ~getservbyname("SE","echo","tcp") then do
  181.         /* failure */
  182.         say "no echo tcp service"
  183.         exit
  184.     end
  185.  
  186.     /* success */
  187.     say "Name:"  se.SERVNAME
  188.     say "Port:"  se.SERVSPORT
  189.     say "Proto:" se.SERVPROTO
  190.  
  191.     if se.SERVALIASES.num=0 then say "No alias"
  192.     else do
  193.         say "Alisases"
  194.         do i = 0 to se.SERVALIASES.num-1
  195.             say se.SERVALIASES.i
  196.         end
  197.     end
  198.  
  199.     ---------------
  200.  
  201.     As you can see, getservbyname() fells on success the fields
  202.  
  203.     - SERVNAME
  204.     - SERVPORT
  205.     - SERVPROTO
  206.     - SERVALIASES.NUM
  207.     - SERVALIASES.0 , ... , SERVALIASES.last ( last = SERVALIASES.NUM-1 )
  208.  
  209.     of the arexx stem that has as root part that stemName you give the
  210.     function as first arguments.
  211.  
  212.     If an array is part of the structure then the number of members
  213.     are returned in X.Y.NUM and the mebers can be found in
  214.     X.Y.0 , .... , X.Y.last last = X.Y.NUM -1 ;
  215.     so if X.Y.NUM == 0 the array is empty.
  216.  
  217.     For each structure the fields read or write by functions are:
  218.  
  219.     - hostent
  220.         - HOSTNAME
  221.         - HOSTADDRTYPE
  222.         - HOSTLENGTH
  223.         - HOSTALIASES.NUM
  224.         - HOSTALIASES.0 , ... , HOSTALIASES.last ( last = HOSTALIASES.NUM-1 )
  225.         - HOSTADDRLIST.NUM
  226.         - HOSTADDRLIST.0 , ... , HOSTADDRLIST.last ( last = HOSTADDRLIST.NUM-1 )
  227.  
  228.  
  229.     - servent
  230.         - SERVNAME
  231.         - SPORT
  232.         - SERVPROTO
  233.         - SERVALIASES.NUM
  234.         - SERVALIASES.0 , ... , SERVALIASES.last ( last = SERVALIASES.NUM-1 )
  235.  
  236.     - protoent
  237.         - PROTONAME
  238.         - PROTOPROTO
  239.         - PROTOALIASES.NUM
  240.         - PROTOALIASES.0 , ... , PROTOALIASES.last ( last = PROTOALIASES.NUM-1 )
  241.  
  242.     - struct sockaddr_in
  243.         passed as argument to functions
  244.         - ADDRFAMILY
  245.         - ADDRPORT
  246.         - ADDRADDR
  247.  
  248.         returned from functions
  249.         - ADDRLEN
  250.         - ADDRFAMILY
  251.         - ADDRPORT
  252.         - ADDRADDR
  253.  
  254.     To make life easier a lots of arguments have their human form and
  255.     can be passed to functions (directly or in as stem field)
  256.     as string.
  257.     They are expecially:
  258.  
  259.     - FAMILY as in socket(family,type,protocol) or ADDRFAMILY
  260.       the internet family that actually has just the string form
  261.       "INET" and MUST BE THAT STRING IN THIS VERSION OF THE LIBRAY!
  262.  
  263.       can be passed as integer too.
  264.  
  265.     - type as in socket(family,type,protocol)
  266.       the type of the socket has the string forms
  267.       "STREAM"
  268.       "DGRAM"
  269.       "RAW"
  270.       "RDM"
  271.       "SEQPACKET"
  272.  
  273.       can be passed as integer too.
  274.  
  275.     - protocoll as in socket(family,type,protocol)
  276.       the protocol of the socket has the string forms
  277.       "IP"
  278.       "HOPOPTS"
  279.       "ICMP"
  280.       "IGMP"
  281.       "GGP"
  282.       "IPIP"
  283.       "TCP"
  284.       "EGP"
  285.       "PUP"
  286.       "UDP"
  287.       "IDP"
  288.       "TP"
  289.       "IPV6"
  290.       "ROUTING"
  291.       "FRAGMENT"
  292.       "RSVP"
  293.       "ESP"
  294.       "AH"
  295.       "ICMPV6"
  296.       "NONE"
  297.       "DSTOPTS"
  298.       "EON"
  299.       "ENCAP"
  300.       "DIVERT"
  301.       "RAW"
  302.  
  303.       can be passed as integer too.
  304.  
  305.       Hehe just few protocoll will work in this version of the libray, but ...
  306.       if you are pretty good in TCP/IP programming you can get same mem
  307.       in arexx, create your own packet, i.e. an icmp packet, filling
  308.       the right values for ip header and icmp header , open a row socket
  309.       setsockopt() socket as IP_HDRINCL and send your own packet :-)))
  310.       Maybe in future versions, general packet creation will be performed.
  311.  
  312. ------------------------------------------------------------------------------------
  313.  
  314. 9. Functions in aplhabetic order:
  315.  
  316.               THIS IS NOT A DOC ABOUT SOCKET FUNCTIONS AT ALL
  317.      REFER TO GOOD SOCKET FUNCTIONS BOOKS OR TO SOCKET.LIBRARY AUTODOC
  318.              FOR USE, ARGUMENTS AND RESULTS OF THESE FUNCTIONS
  319.  
  320. ------------------------------------------------------------------------------------
  321.  
  322. ACCEPT()
  323. Usage: ACCEPT(socket,stem)
  324. <socket/N>,<stem/V>
  325.  
  326. Accepts a connection on socket after a a bind() and listen().
  327. Create and returns a new socket for the connection.
  328. Fills stem with sockaddr_in fields.
  329.  
  330. The function returns -1 for failure. Errno() can be used to get
  331. the error code for failure.
  332.  
  333. ------------------------------------------------------------------------------------
  334.  
  335. ADDR2C
  336. Usage: ADDR2C(addr)
  337. <addr/N>
  338.  
  339. Converts an Internet address - like from resolve - to packed chars.
  340. Usefull when you have to export and address into memory.
  341.  
  342. ------------------------------------------------------------------------------------
  343.  
  344. BIND()
  345. Usage: BIND(socket,stem)
  346. <socket/N>,<stem/S>
  347.  
  348. Tries to "bind" the socket.
  349. "stem" must have set then fields:
  350. - ADDRFAMILY  only "INET" for now;
  351. - ADDRADDR       is an integer indicating the inet addr, i.e. as returned by inet_addr()
  352. - ADDRPORT    is the port you want the socket bind to.
  353.  
  354. The function returns -1 for failure. Errno() can be used to get
  355. the error code for failure.
  356.  
  357. EXAMPLE
  358.  
  359.     sock = socket("INET","DGRAM","IP")
  360.     if sock<0 then do
  361.         say "cannot open socket:" Errno()
  362.         exit
  363.     end
  364.  
  365.     local.ADDRFAMILY = "INET"
  366.     local.ADDRADDR     = 0
  367.     local.ADDRPORT   = 4000
  368.  
  369.     if bind(sock,"LOCAL")<0 then do
  370.         say "cannot allocate port 4000:" Errno()
  371.         exit
  372.     end
  373.  
  374. ------------------------------------------------------------------------------------
  375.  
  376. CLOSESOCKET
  377. Usage CLOSESOCKET(socket)
  378. <socket/N>
  379.  
  380. Closes a socket. "socket" is an integer socketfd returned by socket().
  381.  
  382. The function returns -1 for failure. Errno() can be used to
  383. get the error code for failure.
  384.  
  385. THE SOCKETFD CANNOT BE USED AFTER A CALL TO THIS FUNTION.
  386. INTERNAL RESORCE ARE NOMORE AVAIBLE.
  387.  
  388. ------------------------------------------------------------------------------------
  389.  
  390. CONNECT
  391. Usage CONNECT(socket,stem)
  392. <socket/N>,<stem/S>
  393.  
  394. Connects the "socket" to the socketaddr as defined in "stem".
  395.  
  396. "socket" is an integer socketfd returned by socket(),
  397. "stem" is a valid arexx name, with the fields ADDRFAMILY, ADDRADDR, ADDRPORT
  398. set:
  399. - ADDRFAMILY  can be just "INET" for now;
  400. - ADDRADDR       is an integer indicating the inet addr, i.e. as returned by inet_addr()
  401. - ADDRPORT    the port you want to connect to
  402.  
  403. The function returns -1 for failure. Errno() can be used to get
  404. the error code for failure.
  405.  
  406. EXAMPLE
  407.  
  408.     sin.addrfamily = "INET"
  409.     sin.addrport   = se.SERVPORT       /* from a call to getservbyname() */
  410.     sin.addraddr   = he.HOSTADDRLIST.0 /* from a call to getshotbyname () */
  411.  
  412.     if connect(sockfd,"SIN")<0 then do
  413.         say "connect: error" Errno()
  414.         exit
  415.     end
  416.  
  417. ------------------------------------------------------------------------------------
  418.  
  419. DUP2SOCKET
  420. Usage: DUP2SOCKET(socket)
  421. <socket/N>
  422.  
  423. Duplicates an existing socket descriptor and returns its
  424. value. A new macro internal socket resource is allocated.
  425. Returns the new socketfd on success.
  426. It calls the original dup2socket() function with the second
  427. argument as -1.
  428.  
  429. The function returns 1 fo succes, 0 for failure.
  430. Errno() can be used to get the error code for failure.
  431.  
  432. ------------------------------------------------------------------------------------
  433.  
  434. ERRNO
  435. Usage ERRNO()
  436.  
  437. Returns the current error code.
  438.  
  439. ------------------------------------------------------------------------------------
  440.  
  441. ERRORSTRING
  442. Usage: ERRORSTRING(code)
  443. <code/N>
  444.  
  445. Returns the error string associated with the error code.
  446.  
  447. ------------------------------------------------------------------------------------
  448.  
  449. GETHOSTBYADDR
  450. Usage: GETHOSTBYADDR(stem,addr)
  451. <stem/V>,<addr/N>
  452.  
  453. Fills "stem" by host data, host pointed by "addr".
  454. "stem" is a valid arexx name, "arexx" is an integer inet addr, i.e. as
  455. returned bye inet_addr(), "len" is the address length, "type" is the
  456. address type.
  457.  
  458. The following fields of stem are set:
  459. - HOSTNAME             official name of the host
  460. - HOSTADDRTYPE        the type of address being returned;
  461. - HOSTLENGTH        the length, in bytes, of the address.
  462. - HOSTALIASES.NUM    the number of alternate names for the host, the name of which
  463.   are in HOSTALIASES.0,... HOSTALIASES.i (i=HOSTALIASES.NUM-1)
  464. - HOSTADDRLIST.NUM        the number of network addresses, which are in
  465.   HOSTADDRLIST.0,... HOSTADDRLIST.i (i=HOSTALIASES.NUM-1) as integer.
  466.  
  467. The function returns 1 fo succes, 0 for failure.
  468. Errno() can be used to get the error code for failure.
  469.  
  470. ------------------------------------------------------------------------------------
  471.  
  472. GETHOSTBYNAME
  473. Usage: GETHOSTBYNAME(stem,hostName)
  474. <stem/V>,<hostName>
  475.  
  476. Fills "stem" by host data, host pointed by "hostName".
  477. "stem" is a valid arexx name, "arexx" is an integer inet addr, i.e. as
  478. returned bye inet_addr(), "len" is the address length, "type" is the
  479. address type.
  480.  
  481. The following fields of stem are set:
  482. - HOSTNAME             official name of the host
  483. - HOSTADDRTYPE        the type of address being returned; currently always INET.
  484. - HOSTLENGTH        the length, in bytes, of the address.
  485. - HOSTALIASES.NUM    the number of alternate names for the host, the name of which
  486.   are in HALIASIS.0,... HOSTALIASES.i (i=HOSTALIASES.NUM-1)
  487. - HOSTADDRLIST.NUM        the number of network addresses, which are in
  488.   HOSTADDRLIST.0,... HOSTADDRLIST.i (i=HOSTALIASES.NUM-1) as integer.
  489.  
  490. The function returns 1 fo succes, 0 for failure.
  491. Errno() can be used to get the error code for failure.
  492.  
  493. ------------------------------------------------------------------------------------
  494.  
  495. GETHOSTID
  496. Usage: GETHOSTID()
  497.  
  498. Returns the unique identifier of current host.
  499.  
  500. ------------------------------------------------------------------------------------
  501.  
  502. GETHOSTNAME
  503. Usage: GETHOSTNAME(stem)
  504. <stem/V>
  505. Fills stem with the current host name. Returns an arex boolean.
  506.  
  507. ------------------------------------------------------------------------------------
  508.  
  509. GETPEERNAME
  510. Usage: GETPEERNAME(socket,stem)
  511. <socket/n>,<stem/V>
  512.  
  513. Returns the name of the peer connected to socket "socket".
  514.  
  515. The following fields of stem are set:
  516. - ADDRLEN         the length, in bytes, of the address
  517. - ADDRFAMILY      family
  518. - ADDRPORT        the port number
  519. - ADDRADDR        the addr as integer
  520.  
  521. The function returns 1 fo succes, 0 for failure.
  522. Errno() can be used to get the error code for failure.
  523.  
  524. NO TermiteTCP
  525.  
  526. ------------------------------------------------------------------------------------
  527.  
  528. GETPROTOBYNAME
  529. Usage: GETPROTOBYNAME(stem,proto)
  530. "<stem/V>,<protocol>"
  531.  
  532. Returns local protocol data in stem, from protocol name.
  533.  
  534. The following fields of stem are set:
  535. - PROTONAME                 name of the protocol
  536. - PROTOPROTO                id of protocol
  537. - PROTOALIASES.NUM            the number of alternate names for the protocol, the name of which
  538.   are in PALIASIS.0,... PROTOALIASES.i (i=PROTOALIASES.NUM-1)
  539.  
  540. The function returns 1 fo succes, 0 for failure.
  541. Errno() can be used to get the error code for failure.
  542.  
  543. ------------------------------------------------------------------------------------
  544.  
  545. GETPROTOBYNUMBER
  546. Usage: GETPROTOBYNUMER(stem,protocol)
  547. "<stem/V>,<protocol/N>"
  548.  
  549. Returns local protocol data in stem, from protocol id number.
  550.  
  551. The following fields of stem are set:
  552. - PNAME                 name of the protocol
  553. - PROTOPROTO            id of protocol
  554. - PROTOALIASES.NUM        the number of alternate names for the protocol, the name of which
  555.   are in PALIASIS.0,... PROTOALIASES.i (i=PROTOALIASES.NUM-1)
  556.  
  557. The function returns 1 fo succes, 0 for failure.
  558. Errno() can be used to get the error code for failure.
  559.  
  560. ------------------------------------------------------------------------------------
  561.  
  562. GETSERVBYNAME
  563. Usage: GETSERVBYNAME(stem,hostName,proto)
  564. <stem/V>,<name>,[proto]
  565.  
  566. Fills "stem" with the datas of the broken-out fields of an
  567. entry in the local network services data base, from the name of the service.
  568.  
  569. The following fields of stem are set:
  570. - SERVNAME             the official name of the service
  571. - SERVPORT            the port number at which the service resides
  572. - SERVPROTO         the name of the protocol to use when contacting the service
  573. - SERVALIASES.NUM    the number of the alternate names for the service,
  574.   the name of which are in SERVALIASES.0,... SERVALIASES.i (i=SERVALIASES.NUM-1)
  575.  
  576. The function returns 1 fo succes, 0 for failure.
  577. Errno() can be used to get the error code for failure.
  578.  
  579. NO TermiteTCP
  580.  
  581. ------------------------------------------------------------------------------------
  582.  
  583. GETSERVBYPORT
  584. Usage: GETSERVBYPORT(stem,hostName,proto)
  585. <stem/V>,<port/N>,[proto]
  586.  
  587. Fills "stem" with the datas of the broken-out fields of an
  588. entry in the local network services data base, from the port of the service.
  589.  
  590. The following fields of stem are set:
  591. - SERVNAME             the official name of the service
  592. - SERVPORT            the port number at which the service resides
  593. - SERVPROTO         the name of the protocol to use when contacting the service
  594. - SERVALIASES.NUM    the number of the alternate names for the service,
  595.   the name of which are in ALIASES.0,... ALIASES.i (i=ALIASES.NUM-1)
  596.  
  597. The function returns 1 fo succes, 0 for failure.
  598. Errno() can be used to get the error code for failure.
  599.  
  600. NO TermiteTCP
  601.  
  602. ------------------------------------------------------------------------------------
  603.  
  604. GETSOCKETBASE
  605. Usage: GETSOCKETBASE(stem)
  606. <stem/V>
  607.  
  608. Gets global parameter in the protocol stack.
  609. The original bdsocket.library function is SocketBaseTagList, which is
  610. used to get/set; here we split it in 2 as GETSOCKETBASETAGLIST() and
  611. SETSOCKETBASETAGLIST().
  612.  
  613. You must set the field of "stem" you want to read, then call the function.
  614. The function fills the amy field you set with its current value.
  615.  
  616. The fields accepted are:
  617. - BREAKMASK
  618. - DTABLESIZE
  619. - ERRNO
  620. - ERRNOSTRPTR
  621. - HERRNOSTRPTR
  622. - HERRNO
  623. - LOGMASK
  624. - LOGSTAT
  625. - LOGTAGPTR
  626.  
  627. (Take a look at socket.library/SocketBaseTagList)
  628.  
  629. The function return -1 for failure. Errno() can be used to get the error code
  630. for failure.
  631.  
  632. EXAMPLE
  633.  
  634.     drop a. /* to be sure we don't make a mass :-) */
  635.  
  636.     a.ERRNOSTRPTR=40    /* must be numeric */
  637.     a.BREAKMASK=1        /* can be whatever you want */
  638.     a.HERRNOSTRPTR=2    /* must be numeric */
  639.  
  640.     call GetSocketBaseTagList("A")
  641.  
  642.     say a.ERRNOSTRPTR            ----->Message too long
  643.     say a.BREAKMASK                 ----->4096
  644.     say a.HERRNOSTRPTR             ----->Host name lookup failure
  645.  
  646.  
  647. ------------------------------------------------------------------------------------
  648.  
  649. GETSOCKETEVENTS
  650. Usage: GETSOCKETEVENTS(name,opt,stem)
  651. <name/V>,<opt>,<stem/V>
  652.  
  653. Gets asynchronous socket events. You give to it a name, and
  654. it fill stem the value of "opt"; valid opts are:
  655. - ACCEPT
  656. - CLOSE
  657. - CONNECT
  658. - ERROR
  659. - OOB
  660. - READ
  661. - WRITE
  662.  
  663. Return the socket number or -1.
  664. Errno() CAN'T be user afeter this function.
  665.  
  666. ------------------------------------------------------------------------------------
  667.  
  668. GETSOCKETNAME
  669. Usage: GETSOCKETNAME(socket,stem)
  670. <socket/N>,<stem/V>
  671.  
  672. Returns the current name for the specified socket, filling the fields:
  673. - ADDRLEN
  674. - ADDRFAMILY
  675. - ADDRADDR
  676. - ADDRPORT
  677.  
  678. Return -1 for failure.
  679.  
  680. ------------------------------------------------------------------------------------
  681.  
  682. GETSOCKOPT
  683. Usage GETSOCKOPT(socket,level,name,stem)
  684. <socket/N>,<level>,<name>,<stem/V>
  685.  
  686. Fills stem with value of the opt name associated with
  687. a socket at level "level".
  688.  
  689. For now levels are:
  690.  
  691. -SOCKET
  692. -IP
  693.  
  694. Valid opt for SOCKET are:
  695. - DEBUG
  696. - REUSEADDR
  697. - REUSEPORT
  698. - KEEPALIVE
  699. - DONTROUTE
  700. - LINGER
  701. - BROADCAST
  702. - OOBINLINE
  703. - TYPE
  704. - ERROR
  705.  
  706. The value is written in stem.
  707. If LINGER, the fields ONOFF, LINGER of stem are filled.
  708.  
  709. Valid opt for IP are
  710. - HDRINCL
  711. - IPOPTIONS            just returns a boolean not a buffer!!!
  712. - TTL
  713. - TOS
  714.  
  715. The function returns -1 for failure. Errno() can be used to get the error code
  716. for failure.
  717.  
  718. ------------------------------------------------------------------------------------
  719.  
  720. HELP
  721. Usage: HELP(funName)
  722. <funName>
  723.  
  724. Returns the arguments string of "funName".
  725. This is a "help function" that all my arexx library offer.
  726.  
  727. ------------------------------------------------------------------------------------
  728.  
  729. INETADDR
  730. Usage: INETADDR(addr)
  731. <addr/N>
  732.  
  733. Converts IP address from text to integer form.
  734. Returns -1 on error.
  735.  
  736. ------------------------------------------------------------------------------------
  737.  
  738. INETNTOA
  739. Usage: INETNTOA(hostName)
  740. <addr>
  741.  
  742. Converts IP address from integer to text form.
  743.  
  744. ------------------------------------------------------------------------------------
  745.  
  746. IOCTLSOCKET
  747. Usage: IOCTLSOCKET(socket,req,value)
  748. <socket/N>,<req>,<value/n>
  749.  
  750. Controls "socket" parameters.
  751.  
  752. Actual req value are:
  753. - FIOASYNC
  754. - FIONBIO
  755. - FIONREAD
  756. - SIOCATMARK
  757. (Take a look at bsdsocket.library/IoctlSocket)
  758.  
  759. The function returns -1 for failure.
  760. Errno() can be used to get the error code for failure.
  761.  
  762. ------------------------------------------------------------------------------------
  763.  
  764. LISTEN
  765. Usage: LISTEN(socket,backlog)
  766. <socket/N>,<backlog/n>
  767.  
  768. Listens for connections on a socket.
  769.  
  770. The function returns -1 for failure.
  771. Errno() can be used to get the error code for failure.
  772.  
  773. ------------------------------------------------------------------------------------
  774.  
  775. ISLIBON
  776. Usage: ISLIBON(name)
  777. <name>
  778.  
  779. Tests on what stack the library is working on or if a library is present,
  780. returning a boolean.
  781.  
  782. Value for name are:
  783.  
  784. - MIAMI            running on miami
  785. - TTCP            running on tcp
  786. - USERGROUP        (not yet usefull)
  787.  
  788. ------------------------------------------------------------------------------------
  789.  
  790. OBTAINSOCKET
  791. Usage: OBTAINSOCKET(key,socket,family,type,protocol)
  792. <key/N>,<family>,<type>,[protocol]
  793.  
  794. Obtains a previously released socket.
  795. Only arexx macro released socket can be obtained.
  796.  
  797. ------------------------------------------------------------------------------------
  798.  
  799. OPENCONNECTION
  800. Usage: OPENCONNECTION(proto,port,host,remotePort,stem)
  801. <proto>,<localport>,[host],[remoteport],[stem/V]
  802.  
  803. Let's see the different forms:
  804.  
  805. proto can be the string "tcp" or "udp".
  806.  
  807. res=OpenConnection(proto,4050)
  808.     create a socket
  809.     bind the socket to port 4050
  810.  
  811. res=OpenConnection(proto,"funnyService")
  812.     serach for a local serv entry with the name "funnyService"
  813.     create a socket INET STREAM TCP or INET DGRAM UDP
  814.     bind the socket on the service port
  815.  
  816. res=OpenConnection("tcp","echo","www.nasa.org")
  817.     create a socket INET STREAM TCP
  818.     search for a local serv entry with the name "echo"
  819.     connect the socket to www.nasa.org:echo
  820.  
  821. res=OpenConnection("udp","echo","www.nasa.org")
  822.     ERROR
  823.  
  824. res=OpenConnection("tcp",4000,"www.nasa.org")
  825.     ERROR
  826.  
  827. res=OpenConnection("tcp",4000,"www.nasa.org","echo")
  828.     create a socket INET DGRAM UDP
  829.     bind the socket to port 4000
  830.     search for a local serv entry with the name "echo"
  831.     connect the socket to www.nasa.org:echo
  832.  
  833. Did you understand?
  834.  
  835. Take a look at the examples.
  836. Read same docs for the differeces beetwen conneting a socket
  837. of type tcp or udp.
  838.  
  839. Have fun!
  840.  
  841. The function returns:
  842.  -3 server entry serch failure
  843.  -2 host lookup failure
  844.  -1 bsdsocket.library error
  845. >=0 socket number id
  846.  
  847. If present as the 5th argument and on connection, stem
  848. is filled as socketaddr_in.
  849.  
  850. NO TermiteTCP
  851.  
  852. ------------------------------------------------------------------------------------
  853.  
  854. RECV
  855. Usage: RECV(socket,stem,len,flags)
  856. <socket/N>,<stem/V>,<len/n>,[flags/n]
  857.  
  858. Receives data from "socket". It receives max "len" data and fills "stem"
  859. with the data received.
  860.  
  861. The function returns -1 for failure or data length read.
  862. Errno() can be used to get the error code for failure.
  863.  
  864. ------------------------------------------------------------------------------------
  865.  
  866. RECVFROM
  867. Usage: RECVFROM(socket,bufStem,len,flags,stem)
  868. <socket/N>,<stem/V>,<len/n>,[flags/n],[stem/V]
  869.  
  870. Receives data from "socket". I receives max "len" data and fills "bufStem"
  871. with the data received.
  872.  
  873. if present, "socketStem" is a valid arexx name, with the fields ADDRFAMILY,
  874. ADDRADDR, ADDRPORT set:
  875. - ADDRFAMILY can be just "INET" for now;
  876. - ADDRADDR     is an integer indicating the inet addr, i.e. as returned by inet_addr()
  877. - ADDRPORT   is the "well known" port you want to connect
  878. and it is filled back.
  879.  
  880. If sock is connected
  881.  
  882. recvfrom(sock,buff,len)
  883. recvfrom(sock,buff,len,,)
  884. recv(sock,buff,len)
  885.  
  886. are the same things
  887.  
  888. The function returns -1 for failure.
  889. Errno() can be used to get the error code for failure.
  890.  
  891. ------------------------------------------------------------------------------------
  892.  
  893. RECVLINE
  894. Usage: RECVLINE(socket,bufStem,len,stem,flags)
  895. "<socket/N>,<stem>,<len/n>,[flags/N],<stem>
  896.  
  897. Receives a line from "socket". I receives max "len" data and fills "bufStem"
  898. with the data received.
  899.  
  900. if present, "socketStem" is a valid arexx name, with the fields ADDRFAMILY, ADDRADDR,
  901. ADDRPORT set:
  902. - ADDRFAMILY can be just "INET" for now;
  903. - ADDRADDR     is an integer indicating the inet addr, i.e. as returned by inet_addr()
  904. - ADDRPORT   is the "well known" port you want to connect
  905. and it is filled back.
  906.  
  907.  
  908. The function returns -1 for failure.
  909. Errno() can be used to get the error code for failure.
  910.  
  911. This is a relly bad non buffered readline. Don't use it so much!
  912.  
  913. ------------------------------------------------------------------------------------
  914.  
  915. RELEASECOPYOFSOCKET
  916. Usage: RELEASECOPYOFSOCKET(socket)
  917. <socket/N>
  918.  
  919. Releases a copy of a socket to the public.
  920. The function returns a key string to be used with ObtainSocket().
  921. Don't mess with that key or try to pass ObtainSocket() any other value!
  922. The original socket is still active and private in the macro.
  923. See note in Bugs.
  924.  
  925. The function return a Null() on failure.
  926.  
  927. ------------------------------------------------------------------------------------
  928.  
  929. RELEASESOCKET
  930. Usage: RELEASESOCKET(socket)
  931. <socket/N>
  932.  
  933. Releases a socket to the public.
  934. The function returns a key string to be used with ObtainSocket().
  935. Don't mess with that key or try to pass ObtainSocket() any other value!
  936. The socket is no more active but still in the caller the macro environment.
  937.  
  938. If the socket is not released, it belongs to the caller macro still.
  939.  
  940. The function return a Null() on failure.
  941.  
  942. EXAMPLE
  943.     key = ReleaseSocket(sock)
  944.     if key == Null() then /* failure */
  945.  
  946. ------------------------------------------------------------------------------------
  947.  
  948. RESOLVE
  949. Usage: RESOLVE(host)
  950. <host>
  951.  
  952. Converts IP address from text or name form to integer.
  953. The functions try first a inet_addr() and then a gethosbyname().
  954. Returns -1 or address of host.
  955.  
  956. ------------------------------------------------------------------------------------
  957.  
  958. SEND
  959. Usage: SEND(socket,data,flags)
  960. <socket/N>,<data>,[flags/N]
  961.  
  962. Sends data to a connected "socket".
  963.  
  964. The function returns -1 for failure.
  965. Errno() can be used to get the error code for failure.
  966.  
  967. ------------------------------------------------------------------------------------
  968.  
  969. SENDTO
  970. Usage: SENDTO(socket,data,flags,stem)
  971. <socket/N>,<data>,[flags/n],[stem/V]
  972.  
  973. Send data to "socket".
  974.  
  975. If present "stem" is a valid arexx name, with the fields ADDRFAMILY, ADDRADDR,
  976. ADDRPORT set:
  977. - ADDRFAMILY can be just "INET" for now;
  978. - ADDRADDR     is an integer indicating the inet addr, i.e. as returned by inet_addr()
  979. - ADDRPORT   is the "well known" port you want to connect
  980.  
  981. The function returns -1 for failure.
  982. Errno() can be used to get the error code for failure.
  983.  
  984. ------------------------------------------------------------------------------------
  985.  
  986. SETSOCKETBASE
  987. Usage: SETSOCKETBASE(stem)
  988. <stem/V>
  989.  
  990. Sets global parameter in the protocol stack.
  991. The original bdsocket.library function is SocketBaseTagList, which is
  992. use to get/set; here we split it in 2 as GETSOCKETBASETAGLIST() and
  993. SETSOCKETBASETAGLIST().
  994.  
  995. You must set the field of "stem" with the value you want to set,
  996. then call the function.
  997. The fields accepted are:
  998. - BREAKMASK
  999. - DTABLESIZE
  1000. - ERRNO
  1001. - HERRNO
  1002. - LOGMASK
  1003. - LOGSTAT
  1004. - LOGTAGPTR
  1005. (Take a look at socket.library/SocketBaseTagList)
  1006.  
  1007. The function returns -1 for failure. Errno() can be used to get the error code
  1008. for failure.
  1009.  
  1010. ------------------------------------------------------------------------------------
  1011.  
  1012. SETSOCKOPT
  1013. Usage SETSOCKOPT(socket,level,opt,value,value)
  1014. <socket/N>,<level>,<opt>,[value],{value/N}
  1015.  
  1016. Set value of the opt name associated with a socket at level "level".
  1017.  
  1018. For now levels are:
  1019.  
  1020. SOCKET
  1021. IP
  1022. TCP
  1023.  
  1024. Valid opt for level SOCKET are:
  1025. - DEBUG                N
  1026. - REUSEADDR            N
  1027. - REUSEPORT            N
  1028. - KEEPALIVE            N
  1029. - DONTROUTE            N
  1030. - LINGER            N
  1031. - BROADCAST            N
  1032. - OOBINLINE            N
  1033. - SNDBUF            N
  1034. - RCVBUF            N
  1035. - SNDLOWAT            N
  1036. - RCVLOWAT            N
  1037. - SNDTIMEO            N
  1038. - RCVTIMEO            N
  1039. - EVENTMASK            D    (see GETSOCKETEVENTS)
  1040.  
  1041. If opt is SO_LINGER, SO_SNDTIMEO or SO_RCVTIMEO the 3rd argument can be passed
  1042. (default 0).
  1043.  
  1044. Valid opt for level IP are:
  1045. - HDRINCL        N
  1046. - TTL            N
  1047. - TOS            N
  1048.  
  1049. Valid opt for level TCP are:
  1050. -NODELAY        N
  1051. -MAXSEG            N
  1052. -NOPUSH            N
  1053. -NOOPT            N
  1054.  
  1055. Thes function returns -1 for failure.
  1056. Errno() can be used to get the error code for failure.
  1057.  
  1058. ------------------------------------------------------------------------------------
  1059.  
  1060. SHUTDOWN
  1061. Usage: SHUTDOWN(socket,how)
  1062. <socket/N>,<how/N>
  1063.  
  1064. Causes all or part of a full-duplex connection on
  1065. the socket associated with s to be shut down.  If how is 0, further
  1066. receives will be disallowed.  If how is 1, further sends will be
  1067. disallowed.  If how is 2, further sends and receives will be
  1068. disallowed.
  1069.  
  1070. The function return -1 for failure. Errno() can be used to get the error code
  1071. for failure.
  1072.  
  1073. THE SOCKETFD CANNOT BE USED AFTER THIS FUNTION. INTERNAL RESORCE ARE NOMORE AVAIBLE.
  1074.  
  1075. ------------------------------------------------------------------------------------
  1076.  
  1077. SOCKET
  1078. Usage: SOCKET(family,type,protocol)
  1079. <family>,<type>,<protocol>
  1080.  
  1081. Creates an endpoint for communication and returns a descriptor.
  1082. It also adds to the local-macro list of open sockets a new link so that
  1083. resource can be freed at macro exit.
  1084.  
  1085. It returns a socketfd as integer that must be used in every function
  1086. wich needs a "socket" argument.
  1087.  
  1088. The function returns -1 for failure.
  1089. Errno() can be used to get the error code for failure.
  1090.  
  1091. ------------------------------------------------------------------------------------
  1092.  
  1093. WAITSELECT
  1094. Usage: WAITSELECT(stem,secs,micro,signals)
  1095. <stem>,[secs/N],[micro/N],[signals/N]
  1096.  
  1097. Waits for events on sockets, time, exec signals.
  1098.  
  1099. An example will help.
  1100.  
  1101. Let's suppose we have 2 sockets, sf1 and sf2, and we want to controll
  1102. if something happens about that. We do:
  1103.  
  1104. WAIT.READ.0 = sfd1  /* to wait for ready to be read event */
  1105. WAIT.READ.1 = sfd2
  1106.  
  1107. WAIT.WRITE.0 = sfd1 /* to wait for ready to be written event */
  1108. WAIT.WRITE.1 = sfd1
  1109.  
  1110. WAIT.EX.0 = sfd1    /* to wait for exceptions event */
  1111. WAIT.EX.1 = sfd2
  1112.  
  1113. /* we wait for the events above, or 10 seconds or a signal in sig mask */
  1114. res = WaitSelect("WAIT",10,0,sig)
  1115.  
  1116. /* res may be:
  1117.    < 0 -> error
  1118.    = 0 no events on sockets
  1119.    > 0 number of ready sockets
  1120.  
  1121. To test wich sockets is ready we make a boolean test on WAIT.0.READ
  1122. and so on */
  1123.  
  1124. if WAIT.0.READ then ... /* socket sfd1 is ready to be read */
  1125. ...
  1126.  
  1127. The function returns -1 for failure.
  1128. Errno() can be used to get the error code for failure.
  1129.  
  1130. ------------------------------------------------------------------------------------
  1131.  
  1132. 10. Thanks
  1133.  
  1134.     - thanks to shido for his gift "hi shido you are so great!"
  1135.  
  1136.     - thanks to [X_MaN] who introduced me into the irc world
  1137.       and Internet in general
  1138.  
  1139.     - thanks to "Unix Network Programming"
  1140.  
  1141.     - thanks to Kruse for his wonderfull miami ( "hey man i really
  1142.       hope those rumours about backdoors are not true at all")
  1143.  
  1144.     - thans to poing for his help
  1145.  
  1146.     - thans to Amiga "may it leave for ever!"
  1147.  
  1148. ------------------------------------------------------------------------------------
  1149.  
  1150. 11. Bibliography
  1151.  
  1152.     - Quite all rfc
  1153.  
  1154.     - "Unix Network Programming" - W. Richard Stevens PTR Prentice Hall
  1155.  
  1156.     - socket.library autodoc
  1157.  
  1158. ------------------------------------------------------------------------------------
  1159.  
  1160. 12. To do
  1161.  
  1162.     Very much:
  1163.  
  1164.     - first of all a serious debugging :-)
  1165.  
  1166.     - init_inetd() function
  1167.  
  1168.     - hehe a pretty good reacvline()
  1169.  
  1170.     - direct creation of raw packets, icpm packet and so on.
  1171.  
  1172.     - miami.library functions
  1173.  
  1174.     - higher lever functions
  1175.  
  1176. ------------------------------------------------------------------------------------
  1177.  
  1178. 13.    Note
  1179.  
  1180.     Function to deallocate the local enviroiment in the library base
  1181.     is saved in the fields pr_ExitCode and pr_ExitData of the Process
  1182.     structure of the macro.
  1183.     At the exit a chain of pr_ExitCode(pr_ExitData) is called.
  1184.  
  1185.     The problem is with the inetd that passes copy of the release
  1186.     socket just there, hehe.
  1187.  
  1188. ------------------------------------------------------------------------------------
  1189.  
  1190. 14. Last minute
  1191.  
  1192.     Some functions have been added (they are in another library, i don't
  1193.     want to make pubblic yet). They are:
  1194.  
  1195.     NAME            description                        args
  1196. ------------------------------------------------------------------------------------
  1197.     ALLOCSIGNAL     alloc and retur a signal byte    no args
  1198. *    FREESIGNAL        free an allocated signal byte   <signal/N>
  1199.     OR                 or till 15 long                    {signal/N}
  1200.     AND                and till 15 long                {signal/N}
  1201.     PORTSIGNAL        return byte signal of a
  1202.                     local OPENPORT() port            <portName>
  1203.     WAIT            wait for signals or secs,micro    <signals/N>,[sec/N],[micro/N]
  1204. *    SIGNAL            signal a process                "<task/N>,<signals/N>"
  1205. ------------------------------------------------------------------------------------
  1206.  
  1207.                  THE * MEANS THE FUNCTION CAN BE DANGEROUS
  1208.